README file for JADE $Name: JADE-2_4 $ - Example programs.

Some example programs are provided in JADE package, to show various
framework features and suggested programming idioms.  To run the
examples, you must set CLASSPATH environment variable to contain the
file jade.jar, jadeTools.jar and Base64.jar,iiop.jar and the current directory ('.').
Then change to 'src' directory and refer to the various example agents
with a fully qualified package name; all example agent classes belong
to subpackages of 'examples' package: for example, class ComplexBehaviourAgent
 in 'behaviours' subdirectory of 'examples' directory must be started 
by the jade/src directory with:

      java jade.Boot -platform a1:examples.behaviours.ComplexBehaviourAgent


The following list describes all the example programs found in
'src/examples' subdirectories, detailing their features.



'behaviours' subdirectory
=========================
This examples shows some examples of agent behaviours.

 - ComplexBehaviourAgent.class	An agent with a behaviour made of many 
				steps,with some steps that have sub-steps
                                themselves. This examples shows how
                                jade.core.behaviours.SequentialBehaviour class
                                allows the construction of aggregate
                                behaviours starting from simpler ones,
                                even with recursive aggregations.
                                Besides, it shows the cooperative
                                multitasking presently used for
                                intra-agent behaviour scheduling.
 
 - WakerAgent.class      	This example shows the usage of the WakerBehaviour. 
				The agent object, at its setup, adds 2 WakerBehaviours. 
				The first behaviour wakes up after the given timeout. 
				The second behaviour wakes up at the given date and time.
                                When they wake up, the method handleElapsedTimeout() is 
				executed.
				Notice that in the first behaviour, the execution of the 
				method reset(t) makes repetitive the behaviour itself; 
				that is it wakes up every t milliseconds.


 - FSMAgent.class		An agent with two behaviours built like finite state 
				machines.

 - TestReceiverBehaviourAgent	This agent shows the usage of the 
                                ReceiverBehaviour, the WakerBehaviour, and
                                the SimpleBehavoiour.



'Base64' subdirectory
=====================
This examples shows how to transport serialized Java object over an ACLMessage.
You can execute it, for instance, with the following command:
	
	java jade.Boot -platform a1:examples.Base64.ObjectWriterAgent
	a2:examples.ex7.ObjectReaderAgent

 - ObjectReaderAgent.class	This agent makes the following task: 
				1. registers itself with the df as a reader;
				2. waits a message from its companion, the ObjectWriterAgent; 
				3. reads the content of the message, knowing a-priori that 
   				   it is encoded in Base64 and contains a Java object;
				
	
 
 - ObjectWriterAgent.class	This agent makes the following task:
				1. searches in the DF for an ObjectReaderAgent;
				2. sends an ACLMessage with a content encoded in Base64 to the 
                                   ObjectReaderAgent.

 - Person.class			This is  just a support class for the object reader
				and writer agents.




'jess' subdirectory
===================
JessAgent is a sample agent that allows the programmer to avoid writing any 
line of Java code. He can implement everything in CLIPS by using JESS.
The code IS just the file JadeAgent.clp.
Every time an ACL message arrives, a new fact is asserted in JESS.
A function allows to send messages.
In order to compile this example, JESS is needed. It has been already tested
with JESS 5.1
 - BasicJessBehaviour.class
 - JessAgent.class
 - JessBehaviour.class
 - JadeAgent.clp	


'mobile' subdirectory
=====================
This is an example of mobile agent.
 - CounterBehaviour.class	The behaviour uses two resources, in particular 
				the counter cnt and the flag cntEnabled, of the agent object. 
				It prints its value, increments by one,blocks 
				for two seconds, and repeats forever. 


 - ExecutorBehaviour.class	This is the main behaviour of the Agent. 
				It serves all the received messages. 
				In particular,the following expressions are accepted 
				as content of "request" messages:
				- (move <destination>)  to move the Agent to another container. 
			          Example: (move Front-End) or (move Container-1)
				- (exit) to request the agent to exit
				- (stop) to stop the counter
				- (continue) to continue counting

- MobileAgent.class		This is an example of mobile agent. 
				This class contains the two resources used by the 
				agent behaviours: the counter cnt and the flag cntEnabled. 
				At the setup it adds two behaviours to serve the incoming messages and
				to increment the counter. 
				In particular, notice the usage of the two methods beforeMove() and
				afterMove() to execute some application-specific tasks just before 
				and just after the agent migration takes effect.



'protocols' subdirectory
========================
This example shows the usage of two behaviours provided by JADE 
that implement the 'fipa-query' protocol and the 'fipa-request' protocol.

 - Initiator.class	This agent plays initiator role in a
                        conversation following standard 'fipa-request' or 'fipa-query' protocol.
			It sends a REQUEST, a QUERY-IF or a QUERY-REF to a set of agent passed as argument.
                                
 - Responder.class	The companion agent of Initiator.
                        This agent plays responder role in 'fipa-request' and  'fipa-query' protocol 
			according to the messsage received. 
			If a REQUEST arrives it answers random in one of the following way:
			- send an AGREE message and then an INFORM message
			- send an AGREE message and then a FAILURE message
			- send an AGREE message and then no message (in this case the Initiator agent will wait forever for the INFORM/FAILURE message)
			- send an AGREE message and then an out of sequence message
			- send an INFORM message
			- send a REFUSE message
			- send a NOT_UNDERSTOD message
			- send an out of sequence message
			- send no message

			If a QUERY-IF/QUERY-REF message arrives if replies in one of the following way:
			- sends a NOT_UNDERSTOOD message
			- sends a REFUSE message
			- sends a FAILURE message
			- sends an INFORM message
			- sends an out of sequence message
			- sends no message

 - ProtocolTest.class   This example using the inProcess interface
			permits the user to launch a JADE main container
                        with one Initiator agent and set of Responders, 
                        For examples  the following command line: 
			java examples.protocol.ProtocolTester receiver1 receiver2 receiver3
			start an Initiator agent sending message to the 
			three Responders: receiver1, receiver2 and receiver3.
- ComplexInitiator     This example shows how to use the AchieveREInitiator
                       protocol and register another initiator behaviour
                       to handle one of the states of the protocol. 

-InitiatorHandler      This examples shows an agent sending two different 
			request message to the ResponderHandler agents passed as argument.

-ResponderHandler      This agent performs the role of responder of the message 
			sent by the InitiatorHandler responding with a different
			INFORM according to the action required. ( It shows how to
			use the HandlerSelector state into a AchieveREResponder)


'receivers' subdirectory
========================
This example shows some methods an agent can use to receive a message. 
 
 - AgentSender.class		This agent sends some inform messages.

 - AgentReceiver.class 		This agent receives the messages using different kind 
				of receive methods provided by JADE.


'subdf' subdirectory
====================
 - SubDF.class			This examples shows how to set up multiple
				Agent Domains by means of a network of
				connected Directory Facilitator Agents.
				This agent can automatically
				register itself with another
				DF, and then exploit 
				recursive search capabilities.
				Notice that the same might be done without
				writing any line of code: just start a new
				agent subdf of classe jade.domain.df
				(subdf:jade.domain.df), send it a message
				to request to show the GUI (by using
				the dummyAgent), and then use its GUI
				to federate with its parent.

'ontology' subdirectory
=======================
This examples shows how to use the support for application specific ontologie
provided by JADE.
A very simple ontology (the employment-ontology)including concepts related 
to the employment of people into companies is defined in the package
examples.ontology.employment. The roles in this ontology are
Concepts:
	PERSON
	COMPANY
	ADDRESS
Predicates
	WORKS-FOR - meaning that a person is working for a company
Actions
	ENGAGE - meaning that a person is being engaged by a company
Propositions
	ENGAGEMENT-ERROR - meaning that an error occurred in performing 
				 the engage action
	PERSON-TOO-OLD - meaning that a person cannot be engaged by a 
			     company because he is too old.
The employment subdirectory contains one class for each ontological 
role plus the static class EmploymentOntology that creates an ontology
object and adds to it all the roles described above.

The employment-ontology is used by two agents:
- The RequesterAgent that gets the details of people to engage from
the user and asks the EngagerAgent to actually engage them.
- The EngagerAgent that actually perform the engagement.

The RequesterAgent, before requesting the engagement of a person, queries
the EngagerAgent whether that person is already working for the company 
whose employees are managed by the EngagerAgent.

Some hints about the code are in the followings.
The RequesterAgent has a single cyclic complex behaviour in which
- The details of a person to engage are got from the user. This is
done in the preAction() method.
- A query is sent to the EngagerAgent to check that the indicated person is 
not already working for the indicated company. This is done by following
the FIPA-Query protocol and it is implemented through a FipaQueryInitiatorBehaviour
that is added as a sub-behaviour of the main agent behaviour.
- According to the result of the query, A request is sent to the 
EngagerAgent to actually perform the engagement. This is done following
the FIPA-Request protocol and is implemented through a 
FipaRequestInitiatorBehaviour that is added as a sub-behaviour.
- In the postAction() method the main agent behaviour is reset so that it 
is performed cyclically

In the agent setup, besides the addition of the main behaviour, the name
of the EngagerAgent and the detail of the company where to engage people
are requested to the user.

The EngagerAgent has two behaviours:
- A FipaQueryResponderBehaviour to handle queries about people 
working for a company following a FIPA-Query protocol.
- A FipaRequestResponderBehaviour to handle engagement requests
following a FIPA-Request protocol.
Both behaviours are cyclic. 
The company whose engagement are handled by the EngagerAgent is fixed:
CSELT
Via Reiss Romoli 274
Turin


	
'jsp' subdirectory
==================
This is an example of integration of JADE and JSP kindly provided by Daniel
Le Berre. Look at the tutorial in the documentation.


'PingAgent' subdirectory
========================
This directory contains a simple Ping Agent. This agent registers itself with 
the DF and the waits for ACLMessages. If a QUERY_REF message arrives with content
"ping" then it replies with an INFORM message whose content will be "pong".
For every other message received, except for NOT-UNDERSTOOD, 
it replies with a NOT_UNDERSTOOD message. 
	
	
'MessageTemplate' subdirectory
==============================
This example shows the user the way to define an application specific MessageTemplate.
The WaitAgent agent waits for a REQUEST message from a set of agents the user must provide.
Since the default method in class MessageTemplate does not provide a way to define such a
pattern, the example shows how to create this application specific pattern.
To try the example, the user can start the WaitAgent (from command line when launching 
the platform or via RMA gui ) and  then enters the name of the agents that will 
send messages to this agent (for example start a DummyAgent from the RMA gui and use 
it as sender).
If an REQUEST message will be sent (from one of the expected agent) than the WaitAgent will reply with a INFORM message otherwise no reply message will be sent.

'JadeJessProtege' subdirectory
==============================
This package includes examples for a closer integration of JADE with JESS, 
optionally also with protege. Aspects are
* starting a JADE agent from a running JESS engine
* interactively developing JADE agent behaviour from a JESS console
* protege ontology support for JADE agents in JESS rules
The example has been kindly developed by Oliver Hoffmann (oliver@hoffmann.org)
and it is described by the file 'readme.txt' in its subdirectory.

'inprocess' subdirectory
========================

This example shows how to start a JADE runtime from within an external
application. The InProcessTest class is not a JADE agent, but has its
own main() method instead.
When started, the example launches a JADE main container on the local
host, on port 8888, and a peripheral container, both within the same
JVM. An RMA agent is also started.
If the '-container' option is given, then two non-main container are
started that try to connect to an external main container that must be
already active on the local host, port 1099. Then the platform starts
and kills a DummyAgent and finally it starts the MobileAgent example.
Using this example and the regular jade.Boot loader, hybrid platforms
(i.e. platform that live partly in-process and out-of-process) can be
deployed. The two following examples list the commands to issue in
order to create two sample hybrid platforms

  Example 1: In-process main container and out-of-process additional container.
  a) java examples.inprocess.InProcessTest (one main container and an additional one)
  b) java jade.Boot -container -port 8888 (an out-of-process container, connecting to the in-process platform).

  Example 2: Out-of-process main container and in-process additional containers.
  a) java jade.Boot -gui (on out-of-process main container, listening on port 1099)
  b) java examples.inprocess.InProcessTest -container (an in-process container, connecting to the out-of-process platform).


'thanksAgent' subdirectory
========================
This agent implements the following functionality:
 - When being born one will register 
 - It will create a list of agents registered in DF.
 - It will send a message to them of greeting 
 - It will listen if there is some answer 
 - To the agents who answer it will thank to them to answer. 
